<?php

/**
 * AfroSoft ACL API
 *
 * @cond COMPLETE_DOCS
 *
 * Every database connector used by the API must extend this class, as it
 * provides the functions and members than must be defined for normal operation.
 *
 * @package DB
 *
 * @author AfroSoft
 * @version @build.version@ (Build @build.number@)
 * @license http://www.mozilla.org/MPL/MPL-1.1.txt MPL 1.1
 * @copyright Copyright (c) AfroSoft
 */

/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is the AfroSoft ACL API.
 *
 * The Initial Developer of the Original Code is AfroSoft.
 * Portions created by the Initial Developer are Copyright (C) 2011 the Initial
 * Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Xavier L. <xavier.l@afrosoft.tk>
 *
 * ***** END LICENSE BLOCK ***** */
abstract class ACL_DB_Interface {

    /**
     * This array holds the parameters for the current connection.
     */
    private $connectionParams = array(
        'prefix' => null,
    );
    /**
     * This variable holds the connection object for the current connection.
     */
    private $connection = null;


    /**
     * Database class constructor. Sets the connection parameters and connects
     * to the database.
     */
    public abstract function __construct(array $param);

    /**
     * Returns the permission level of specified item.
     * 
     * The parameters used with this function are:
     * - user : the user ID linked to the permission needed
     * - group :  the group ID linked to the permission needed
     * - key : the item key for the permission needed
     * - explicit : a boolean. If set to true, the default permission will not be used.
     *
     * @param array $param
     */
    public abstract function getPermission(array $param);

    /**
     * Returns all the permissions set for users/groups.
     * 
     * The parameters used with this function are:
     * - type : either 'user' or 'group'
     * - id : if set, the id of the user or group for which the permissions are 
     *  fetched
     *
     * @param array $param
     */
    public abstract function getAllPermissions(array $param);

    /**
     * Adds permission to a specified item.
     * 
     * The parameters used with this function are:
     * - id : the ID of the user or group to which the permission should be 
     *  added
     * - type : either 'user' or 'group'
     * - key : the item key on which the permission should be set
     * - permission : the permission to set, in a form of a boolean (false =
     *  deny)
     * 
     * @param array $param
     */
    public abstract function addPermission(array $param);

    /**
     * Edits a permission to a specified item.
     * 
     * The parameters used with this function are:
     * - id : the ID of the user or group whose permission should be modified
     * - type : either 'user' or 'group'
     * - key : the item key on which the permission should modified
     * - new_user : the modification of the user ID
     * - new_group : the modification of the group ID
     * - new_key : the modification of the key
     * - new_permission :  the modification of the permission
     *
     * Only one of the parameters with the 'new_' prefix must be specified.
     *
     * @param array $param
     */
    public abstract function editPermission(array $param);

    /**
     * This functions removes custom permission associated with a key and a 
     * user or group.
     * 
     * The parameters used with this function are:
     * - id : the ID of the user or group from which to remove the permission
     * - type : either 'user' or 'group'
     * - key : the key associated with permission to remove
     *
     * @param array $param
     */
    public abstract function revertPermission(array $param);

    /**
     * Returns an item.
     * 
     * The parameters used with this function are:
     * - key : the key for which to retrieve the record.
     *
     * @param array $param
     */
    public abstract function getItem(array $param);

    /**
     * Returns all the items.
     * 
     * There are no parameters accepted by this function.
     */
    public abstract function getAllItems();

    /**
     * Adds a non-existing item.
     * 
     * The parameters used with this function are:
     * - key : the key of the item to add
     * - name : the human-readable name for the item to add
     * - desc : the description of the item to add
     * - default : the default permission to set, in a form of a boolean
     * (false = deny)
     * 
     * @param array $param
     */
    public abstract function addItem(array $param);

    /**
     * Edits an existing item.
     * 
     * The parameters used with this function are:
     * - key : the item key for which the record should be modified
     * - new_key : the modification of the key
     * - new_name : the modification of the name
     * - new_desc : the modification of the description
     * - new_default :  the modification of the default permission
     *
     * Only one of the parameters with the 'new_' prefix must be specified.
     *
     * @param array $param
     */
    public abstract function editItem(array $param);

    /**
     * Removes an item.
     * 
     * The parameters used by this function are:
     * - key : the key for which the record should be removed.
     *
     * @param array $param
     */
    public abstract function removeItem(array $param);
}

/** @endcond */
